<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
  <title>LADOSC Specification</title>
  <meta name="generator" content="emacs" />
  <link href="using-ladosc-files/ingen-large.png" />
</head>

<body style="background-color: Grey;">
<a href="using-ladosc.html">main ladosc documentation</a>
<h2>behaviour overview</h2>
<p>The ladosc <em>osc in</em> plugin recieves UDP messages following
  the OSC specification. The path listened to is "/lad_osc", all other
  paths are silently ignored. The message format understood is "ff",
  two single precision floating point values. All other message
  formats are silently ignored. The first floating point value is
  interpreted as an index, and the second as a scalar value. If
  <code>index_start <= index <= index_start+15</code>, the
  output port number <code>index-index_start</code> reports the scalar
  value from the message. If the value is not read and acted on by
  another plugin before a new value is recieved for that port, the
  value is lost.</p>
<p>The ladosc <em>osc out</em> plugin send UDP messages following the
  OSC specification. The path transmitted is "/lad_osc", designed of course
  for compatibility with the <em>osc in</em> plugin, but they should be easy
  enough to use seperately. The message format sent is "ff", two floating
  point numbers. Both values are sent whenever either one changes on the LADSPA
  input, and no messages are sent for inputs that are identical to the previous.
  To clarify, here are the outputs for inputs recieved in the following order:
  <table border="1" summary="input/output examples for osc out">
    <tr>
      <td><strong>LADSPA Input 1</strong></td>
      <td><strong>LADSPA Input 2</strong></td>
      <td><strong>OSC Output</strong></td>
    </tr>
    <tr>
      <td>1.0</td><td>0.0</td><td>"ff" 1.0 0.0</td><td>the initial state is
	always sent</td>
    </tr>
    <tr>
      <td>1.0</td><td>0.0</td><td></td><td>duplicate inputs are ignored</td>
    </tr>
    <tr>
      <td>1.0</td><td>0.0</td><td></td><td></td>
    </tr>
    <tr>
      <td>1.0</td><td>0.001</td><td>"ff" 1.0 0.001</td><td></td>
    </tr>
    <tr>
      <td>NaN</td><td>INF</td><td>"ff" NaN INF</td><td>values are not used, so
	invalid values are passed on silently</td>
    </tr>
  </table>
</p>
<h1>osc in</h1>
The <em>osc in</em> plugin creates an OSC server. It has the following
controls:
<table border="3" summary="the parameters of the osc in plugin">
  <tr>
    <td><strong>Parameter</strong></td>
    <td><strong>Minimum Useful Value</strong></td>
    <td><strong>Maximum Useful Value</strong></td>
    <td><strong>Parameter / Input / Output</strong></td>
  </tr>
  <tr>
    <td><code>port</code></td>
    <td>49152</td>
    <td>65535</td>
    <td>Parameter to <code>connect</code></td>
    <td>The port number on which to listen, lower values can be used, if you
      don't mind stealing a port used by a
      <a href="http://www.iana.org/assignments/port-numbers">known UDP
	service</a>.
    </td>
  </tr>
  <tr>
    <td><code>index_start</code></td>
    <td>-15</td>
    <td>999</td>
    <td>Input</td>
    <td>The OSC input index that will be reported on
      LADSPA <code>out_0</code>, LADSPA <code>out_1</code> will report
      inputs to the OSC index <code>index_start+1</code>, etc. on to
      LADSPA <code>out_15</code> reporting inputs to OSC
      index <code>index_start+15</code>. All other input indexes are
      dropped</td>
  </tr>
  <tr>
    <td><code>connect</code></td>
    <td>0</td>
    <td>1</td>
    <td>Input</td>
    <td>A transition in value from 0 to 1 causes this plugin's OSC server
      to be started in a new thread, on the port specified by
      the <code>port</code> parameter. A transition from 1 to 0 causes
      the server to be shut down, if it is currently running. Please
      don't take for granted any particular rounding behaviour in
      between the values 1 and 0.</td></tr>
  <tr>
    <td><code>status</code></td>
    <td>unknown</td>
    <td>unknown</td>
    <td>Output</td>
    <td>In future versions, this will report the status of the OSC server
      thread. liblo0 provides no way to differentiate server instances in it's
      error callback, so for now it does nothing.</td>
  </tr>
  <tr>
    <td><code>out_0</code> through <code>out_15</code></td>
    <td>Negative Infinity</td>
    <td>Infinity</td>
    <td>Output</td>
    <td>This is a value sent from an OSC client. It is not verified,
      sanitized, examined, or tested in any way (not even to check for
      an error throwing NaN). Furthermore, there is also no client
      verification, no session verification, and no filtering, so use
      this data at your own risk. <code>out 0</code> will receive OSC
      inputs tagged with an index field of <code>index_start</code>,
      and <code>out 15</code> receives inputs tagged with an index
      of <code>index_start+15</code>, and so on in between.
    </td>
  </tr>
</table>
<h1>osc out</h1>
The <em>osc out</em> plugin creates an OSC transmitter. It has the following
controls:
<table border="3" summary="the parameters of the osc in plugin">
  <tr>
    <td><strong>Parameter</strong></td>
    <td><strong>Minimum Useful Value</strong></td>
    <td><strong>Maximum Useful Value</strong></td>
    <td><strong>Parameter / Input / Output</strong></td>
  </tr>
  <tr>
    <td><code>port</code></td>
    <td>49152</td>
    <td>65535</td>
    <td>Parameter to <code>connect</code></td>
    <td>The port number on which to transmit.</td>
  </tr>
  <tr>
    <td><code>octet_1</code> through <code>octet_4</code></td>
    <td>0</td>
    <td>255</td>
    <td>Parameter to <code>connect</code></td>
    <td>The four octets describe the IP address to connect to. Most of the time
      this will be 127.0.0.1, ie. localhost</td>
  </tr>
  <tr>
    <td><code>connect</code></td>
    <td>0</td>
    <td>1</td>
    <td>Input</td>
    <td>A transition from a value of 0 to a value of 1 causes a transmitter
      resource to be allocated for the IP address described by
      <code>octet_1</code> through <code>octet_4</code>. Repeated values of 1,
      after the initial one, are ignored. A transition from a value of 1 to a
      value of 0 causes the transmitter resource to be deallocated. Repeated
      values of 0, after the initial one, are ignored. Any fractional numbers,
      or numbers outside this range, are uspecified in their consequences.
    </td>
  </tr>
  <tr>
    <td><code>input</code> and <code>index</code></td>
    <td>Negative Infinity</td>
    <td>Infinity</td>
    <td>Input</td>
    <td>Any change in either of these inputs, from the previous value, will
      result in a message, with both values, to be sent, if the OSC transmitter
      is active. Repeated reception of the same LADSPA input will not trigger
      any OSC transmition.</td>
  </tr>
  <tr>
    <td><code>status</code></td>
    <td>?</td>
    <td>?</td>
    <td>Output</td>
    <td>The last nonzero value returned by lo_address_errno is displayed here,
      lo_address_errno is displayed after each message sent. This is mostly for
      host use, humans will probably prefer the string corresponding to the
      error, which  is displayed to the standard error port.</td>
  </tr>
</table>
</body>
</html>
